Languguage OS 2/Languguage OS II Version 10-94 (Knowledge Media)(1994).ISO/language/pcpil/pidoc3.txt

Text File | 1994-02-28 | 36KB | 971 lines

FONT CHARACTER SPACING

Each character of a font has a pixel width associated with it. When the
character is displayed the text cursor advances by that width. The font also
has a line spacing value associated with it. The line spacing value
determines how many pixels are to occur between text lines (vertical
spacing).


FONT CHARACTER DISPLAY

In font display mode characters have transparent backgrounds. That is, only
pixels that are on are written to the screen. So a character cell around the
character is not cleared. The XOR writing mode can be set via the TYPE SCREEN
statement to cause characters to be blended with the current display. If XOR
writing mode is off then characters are painted over the display.

Because of the way in which characters are displayed, it is possible to
overtype characters in a manner similar to on a typewriter producing the
combined effect of more than one character.

To remove a character from the screen, position the cursor to the exact
location of the character, set the XOR writing mode (TS:O1) then type the
same character again.

See also: NH:, Font Editor

NEW KEY - define keyboard codes


       NX: x,y ; x,y . . .
       NXS:

The NX: statement may be used to change the code generated by any key on the
keyboard. The normal codes generated are shown in appendix B. The number x
shown above stands for the normal default value of a key, the letter y stands
for the new value to be generated by the key. Both numbers are always in the
range 0 to 255. Any number of keys may be redefined in one NX: statement.
Each x,y pair is separated from the next by a semi-colon.

Once a key has been redefined it affects all ACCEPT statements except those
with the X modifier. The X modifier on an ACCEPT statement causes any key re-
definitions to be ignored for that ACCEPT.

The NXS: statement causes all keyboard keys to revert to their default
values. NXS: undoes the effect of all previous NX: statements.

EXAMPLE 1: new keys

       R: cause key f1 to generate code 225 (Beta)
       NX: 187,225

       R: cause upper case A to give a-accent
       NX: 65,160
       . . .
       R: restore upper case A to normal
       NX: 65,65

See also:  ACCEPT

PROBLEM - set options


       PR: option-list
       P:  option-list
       PS: list

PROBLEM has two uses.  The first is to provide a destination point for a J:@P
statement.  In this case PROBLEM can be put at the very end of each frame or
question.  The option list would usually be omitted in this case. If the
option list is omitted, then all options retain the settings prior to the
PROBLEM statement.

The second use is to specify one or more lesson options.  Lesson options
control various aspects of student responses, such as automatic case
conversion of student answers or the student response time limit. Each option
can be set (turned on) or it can be reset (turned off).

The option-list consists of one or more of the option letters below.  If the
S modifier is not appended to the op code, then all options not included in
the option-list are cleared or turned off.  If the S modifier is appended to
the op code (PS:), then options previously set remain set.  Each option is
then set if the corresponding letter is present in the option list. The
possible options are shown here.

U  -  if set, all student responses translated to upper case

L  -  if set, all student responses translated to lower case

S  -  if set, all spaces are removed from student responses

G  -  if set, the GOTO command is enabled

E  -  if set, the ESCAPE command is enabled

F  -  if set, the function key ESCAPE command is enabled

I  -   if set,  error messages suppressed

Error messages are not displayed, but the E flag is still set.

Kname  -  set KEEP file name

Sets the file name used by subsequent KEEP statements to name. name can be
any file or path name per DOS conventions.

W  -  clear label table

Clears the label table and forgets about all labels passed so far.  Thus it
is impossible to jump backward.  This allows re-use of the same labels. (Not
recommended for use, present for compatibility only.)

An  -  set answer maximum length

Sets maximum ACCEPT response length to n characters. n may be a number from 1
to 256.  A value of n less than 1 or greater than 256 sets the maximum
response length to 256.

Z  -  causes U, L, S, G, P and E options to be turned off

Tn  -  set answer time maximum

Set max Accept response time to n seconds, where 1<n<32767. T0 sets back to
no limit.

P -  turn on printer echo

Turn "printer-echo" on. Once on then all characters typed to the display are
also sent to the system printer. It is up to the user to insure that the
printer is on and ready since the program can be delayed if it is not ready.
Use the Z option above to turn "printer-echo" off.

Note:  The "R" of "PR:" may be omitted.  It is allowed for COMMON PILOT
compatibility.

EXAMPLE 1: Problem statements

       P: T10
                             - response limit=10 sec
       P: U S
                             - upper case, spaces removed
       P: F
                             - enable FUNCTION key escape
       PS:G
                             - set GOTO, leave others as before
       P:P
                             - turn printer-echo on

See also:  ACCEPT, KEEP, GOTO AND ESCAPE

POKE,OUT - set memory or do output


       PX:offset,value
       PJ:address,value

These statements are not normally used. They are provided for the programmer
who has need to program directly at the hardware level.

The value must be a number or expression from  0 to 255. PX: stores the byte
value in memory at the offset given. The offset is from a segment whose base
is specified by the system variable %A. Great care must be taken in using
this statement as a mistake can cause system failure.

PJ: Performs a machine level OUT instruction to the device address given of
the byte value.

EXAMPLES:

If you have both types of video adapters (monochrome and color) you can
switch from the monochrome to the color for PILOT output via ...

       C: %A=0
       PX: 1040,pek(1040)-16
       (then set desired mode via TS: statement)

and you can change back to the monochrome via...

       C: %A=0
       PX: 1040,pek(1040)+16
       (then set desired mode via TS: statement)

Note: the above example is given for illustration purposes only. The TS:
statement provides a simple way to change video adapters.

REMARK - program comment

       R: remarks

REMARK is ignored during program execution.  It can be used to document a
PC/PILOT program.

EXAMPLE:

       R: This section displays the main menu.


SOUND - generate tones

       S: list

SOUND is used to generate simple tones, noises or beeps for audio feedback.
The list contains one or more pitch or pitch,duration values.  The entries in
the list are separated by the ";" character.  The two possible forms of a
list entry are:

       pitch
       pitch, duration

where pitch is a number or variable from 0 to 2047 and duration is a number
or variable from 1 to 63.  A duration of 34 gives about a one second tone.
The lower the pitch value the higher the tone.  The higher the duration
value, the longer the tone is played.  If the duration is omitted after a
pitch (first form above) then the duration of the previous pitch is used. A
pitch or duration value can be an integer number, a variable name, or an
expression enclosed in parentheses.

It is possible to repeat a series of notes by the notation:

       *n(list)

where n is a number or a variable. A pitch value of 0 give silence. Normally,
doubling a pitch lowers it by one octave. Halving a pitch raises it by one
octave.

EXAMPLES:

       S: 200,25;300,8;100,18
       S: *4(208,5;224)
       R: next two lines play a two-octave scale
       S: 500,10;446;400;374;333;301;266;250
       S: 250,10;223;200;187;166;150;133;125

TYPE - display text on screen


       T: text
       TH: text
       TX: text
       : text

The TYPE statement is used to display text on the screen. TYPE might be used
to provide narrative, instructions, questions, feedback or computational
results. The data you place after the colon is displayed on the screen.

EXAMPLE 1: simple TYPE statement

       T:We will now discuss stock options.

The text is always displayed within the currently defined viewport. Any
display data outside the current viewport is unaffected by the TYPE. The use
of a viewport is explained under the TYPE SCREEN statement. The text is
placed at the current cursor location, advancing the cursor, automatically
wrapping to the start of a new line if necessary.  Unless otherwise
specified, the cursor is returned to the start of the next line within the
viewport. If necessary, the viewport is scrolled up one line to accommodate
the text.


TYPE HANG, SUPPRESS NEW LINE

Appending the H, or hang, modifier to the TYPE, TH:, suppresses the automatic
return to the next line at the end of the text. Instead, the cursor is left
at the position immediately after the last displayed text character.


CURSOR POSITIONING

You can use the TS:, or TYPE SCREEN statement to move the cursor to any
desired screen location.


CLEARING THE SCREEN

Appending the X, or clear, modifier to the TYPE, TX:, clears the viewport and
moves the cursor to home position prior to the text display. Home position is
the upper left corner of the viewport.


CONTINUATION OF A TYPE

A TYPE statement may be continued on the next line by starting the next line
with a colon. You may continue a TYPE in this manner for any number of lines.

EXAMPLE 2: continuation of a TYPE

       T:Point D is the
       :
       :   A  mean
       :   B  median
       :   C  mode


TYPING A $ OR A # CHARACTER

Since PILOT uses the $ and the # as special characters within a TYPE, to
actually display one of these characters, place two adjacent $ or #
characters in the text. For example

       T:You owe $$5.00.

would actually display  "You owe $5.00."


TYPING VARIABLES OR EXPRESSIONS

You can type the value of a variable or an expression within the text. To
type the value of a variable precede the variable name by a "$" or a "#", and
follow the variable name by a space.  The value of the variable will be
displayed at the corresponding place. The name of the variable and the space
after the variable name are not displayed.

EXAMPLE 3: variables in a TYPE

       T:You got #X  right.
       might display    You got 37 right.

       T:This is an example of $ABC$  learning.
       might display
       This is an example of cognitive learning.

In the first example, X is a numeric variable, whose value, 37, is
substituted in the displayed text. In the second example, ABC$ is a string
variable whose value, "cognitive", is substituted in the displayed text. Do
not be confused by the notation, $ABC$. The first $ indicates that a variable
is included in the text of a TYPE statement. The second $ is actually part of
the string variable name ABC$, since all string variable names end with a $.

Programming note: By PILOT language convention, the $ is usually used to
precede a string variable and the # is used to precede a numeric variable. In
fact, this implementation of PILOT allows you to use either symbol for either
type of variable.

The text may contain an expression preceded by a # or $ and enclosed in
parentheses.  The value of the expression is displayed in the text.

EXAMPLE 4: expression within TYPE

       T:The total is #(A+B+C) .
       might display    The total is 102.


TEXT AND BACKGROUND COLORS

The current text and background colors can be changed within the text of a
TYPE. To set the text color put a # followed by a number. To set the
background color put a $ followed by a number. This facilitates the use of
color to highlight a word or phrase within a sentence. The number may be one
or two digits only.

EXAMPLE 5: changing colors

       T:The #2 civil #3 war ended in $011865.

The word "the" is displayed in whatever the text color was prior to this
statement. The word "civil" is displayed in color 2, the word "war" is
displayed in color number 3. Note that 1865 is printed in background color 1.
Only the 01 makes up the background color number since it is two digits.


EXTENDED AND USER-DEFINED

CHARACTERS

All characters, from character code 32 to 255 can be displayed. Codes from 0
to 31 not reserved for control characters may also be displayed via a command
such as  T:$(CHR(25)).  Codes from 32 to 127 are the standard ASCII
characters. Character values from 128 to 255 are used in text modes for the
extended character set built into the computer. In graphics modes, codes 128
through 255 are available for user-defined characters.


CHARACTER FONTS

The NS: statement can be used to change to a character font for all text
output. Character fonts can be used to display characters of all sizes and
styles. See the NS: statement for more information on the use of character
fonts.


XOR TYPE MODE

In graphics modes 4, 5 and 6 the text can be displayed in one of two ways.
The normal way is to display the character in the character cell such that it
writes over the previous display data in the cell.  The second way is called
XOR mode. XOR causes the text to be combined with any display data that may
already be in the character cell on the screen. This is accomplished by a
logical exclusive or of the character pattern with the display screen. The
effect is to not obscure previous graphics data that may have been in the
character cell. Thus it would be possible to have a line or other graphic
element pass right through a character.  The TYPE SCREEN statement is used to
select the character writing mode.


CONTROL CHARACTERS

These cursor control characters may also be output by placing within an
expression or string variable.

       CHR(8) =BACKSPACE
       CHR(9) =FORWARD SPACE
       CHR(10)=DOWN
       CHR(11)=UP
       CHR(12)=CLEAR
       CHR(13)=NEWLINE
       CHR(14)=HOME

DOWN and NEWLINE scroll the viewport up if the cursor is on the bottom line.
UP scrolls the viewport down if the cursor is on the top line.


See also:  TYPE SCREEN, NEW CHARACTER

TYPE SCREEN - set screen options


       TS: command-list

TYPE SCREEN is used to control screen modes and colors, define viewports on
the screen, set line spacing and create animated character graphics.

The command-list consists of one or more of the following commands.  Each
command is separated from the next by a ";" character.  In the command
descriptions below lower case letters denote a numeric variable, integer
constant, or an expression enclosed in parentheses.

Mn - set mode

Set screen mode and erase screen. Screen modes are 0 through 6. On the IBM
EGA modes 13, 14 and 16 are also supported.

MnC - set mode and select color adapter

Placing C after the number switches to the color adapter card.

MnM - set mode and select monochrome adapter

Placing an M after the number switches to the monochrome adapter card. These
two options are only used if you have both types of display adapters and wish
to switch back and forth.

Ln - set line spacing

Set spacing between text lines, n<=1 sets single spacing,  n=2 sets double
spacing, etc..

Fn - set foreground color

Set foreground text color, possible values shown below.

Fn,a - set color palette register

Supported only on EGA. Sets a color in the logical color palette register for
color number n.  Logical color n is set to actual color a. All display data
currently displayed in color n changes immediately to color a.

Bn - set background color

Set background color, possible values shown below.

En - erase to background color

Set background color and clear the current  viewport to the background color;
cursor set to home position in viewport.

Rs,c,r - draw a rectangle outline

A rectangle is drawn with the upper left corner at the current cursor
location. The rectangle is c character cells wide and r character rows deep.

In text mode, if the value for s is 1 or 2 then the rectangle is drawn with
the special line drawing characters of the extended character set, using the
appropriate horizontal, vertical and corner line characters. A value of 1
indicates single line characters, a value of 2 indicates double line
characters. A value of s=0 in text mode indicates that only blanks are
written. This implies that by setting the background color to the desired box
color a box of the background color is drawn.

In graphics mode the value of s=0 indicates that the "*" character is to be
used to draw the box. A value of 1 or two indicates the use of the same
characters used in text mode to draw single and double line rectangles. But
since these characters are in the user-defined range, the actual border
character patterns used are as defined by the program.

On - set overlay mode to xor or normal

Sets the graphics and text overlay mode to normal for n=0, or to XOR mode for
n=1.  Cn - control cursor

Controls the cursor appearance. If n is zero, the cursor is invisible. If
using a text mode, then n=1 gives the normal underscore cursor, and n=2 gives
a block cursor. If using graphics mode, then n is the character number, from
1 to 255 to be used as the cursor. The normal cursor is n=95, the underscore
character.

Xn - set border color

In modes 0-3 sets color of the border or  outer  frame of  the  screen,  in
modes  4 and 5 has same effect as Bn,  in mode 6 sets the text color.

Vl,r,t,b - select viewport

Set screen viewport to be from column l on the left through column r on the
right  and  from  row t  on  the  top through  row b on  the  bottom.   See
below for more information.

V; - restore previous viewport

Restores the previous viewport and cursor position.

Atext - animate text block

Animate: the text is displayed from the cursor position. If the text contains
a "/" character, the "/" is not displayed but the next character is displayed
on the next line down and directly under the original cursor location. Text
is displayed up to a ";" or to the end of the statement.  After the text is
displayed the cursor is left where it was when the animate began. This
command is useful to draw figures made up of a block of several redefined
characters.

A$var$ - animate a string variable

Animate as described above using the contents of the string variable as the
text.

Pn - select display page

Display text page n. In modes 0 and 1 n may be 0-7, in modes 2 and 3 n may be
0-3, in modes 4-6 n may be 0 only. In the text modes (0-3) there are multiple
display pages, one of which is the currently visible page on the screen. The
normal default is PO.

Pn,w - select display and writing page

Displays text page n but makes text page w the current page to be written on
by TYPE statements. Thus the student can view one page while the program
prepares another page for display. The TEXTWIPE utility (AFL) may be useful
in manipulating text pages.

Dn - delay

Delay for n 60ths of a second. This is useful when using animate within a
loop to move a figure on the screen.

Wrlud - walk cursor

Walk right, left, up or down. The W can be followed by any number of r, l, u,
or d characters. Each one moves the cursor one space in the indicated
direction.  Moving down on the bottom line of a viewport causes the viewport
to scroll up; moving up on the top line causes the viewport to scroll down.

Gx,y - goto column, row

Position the cursor in column x and row y of the current viewport. G0,0 goes
to the home position of the viewport.

*n(... ) - loop

Repeats the commands in parentheses n times. Any of the above commands may be
in the parentheses. This is useful to move a figure by repeating a sequence
of animate, delay and walk.


VIEWPORTS

A viewport is a section of the screen which is used to display all text
output by the program.  When PILOT starts the current viewport is defined to
be the entire screen (V0,39,0,24).  The Vl,r,t,b command defines a new
section of the screen to be the current viewport.  When this is done the
cursor is placed in the home position of the viewport.  All text displayed by
the program is displayed only in the current viewport, any data displayed
outside the viewport is unaffected as the viewport changes, clears, scrolls,
etc..

A V command without the four numbers puts the viewport and cursor back to the
position prior to the last V command.  This simplifies alternating between
two viewports on the screen, and is useful for student responses and program
feedback.  Viewports are also useful to retain instructions, questions or
graphs outside a viewport while conversation takes place within the viewport.

EXAMPLE 1: Establishing a viewport from column 5 through
column 30, and from row 18 through row 25, inclusive.

       TS:V5,30,18,25


SCREEN MODES

There are several possible screen modes. Each mode allows different screen
characteristics.  Modes 0 through 3 are called TEXT modes since only text,
not graphics, can be displayed in these modes. Modes with numbers 4 or higher
are called GRAPHICS modes since both text and graphics can be displayed.


TEXT MODES

In the text modes there are either 40 or 80 columns across.  There are always
25 lines of text.  Each character cell has a unique background color, and a
foreground or text color. Characters from the standard ASCII and extended
character set can be displayed. There are 16 possible colors available.

GRAPHICS MODES

In the graphics modes there may be 40 columns or 80 columns, and 25 lines of
text. The text may consist of the standard ASCII characters or the 128 user-
definable characters.  The background color is a screen-wide attribute, that
is, when the background color is selected, the entire screen background
changes immediately. In these modes, the GRAPHICS statement may be used to
draw turtle graphics or display full screen graphics images. There are two
possible 4-color sets, each with two possible intensities.


THE 16 AVAILABLE COLORS

There are 16 standard colors available. Some modes permit the display of all
16 at once, others permit display of a subset of the colors. These color
numbers run from 0 to 15. The colors from 8 through 15 are brighter versions
of the same colors in the range 0 through 7.

          0 - black
          1 - blue
          2 - green
          3 - cyan
          4 - red
          5 - magenta
          6 - brown
          7 - grey

Color 14 (brighter brown) is yellow. Color 15 (brighter grey)
is white.


MODES 0 AND 1

Text modes, 40 columns, 25 lines, text colors 0-15, background colors 0-7,
adding 8 to background causes blinking, no graphics, available on all
graphics adapters. Each character cell on the screen has its own background
and foreground attribute. When a character is written to the display the
character cell takes on the attribute according to the current foreground and
background settings.


MODES 2 AND 3

Text modes, 80 columns, 25 lines, text colors 0-15, background colors 0-7,
adding 8 to background causes blinking, no graphics, available on all
graphics and monochrome adapters. Each character cell on the screen has its
own color attributes as described above for modes 0 and 1.


MODES 4 AND 5

Graphics modes, 40 column text, 25 text lines, 320 pixels across, 200 pixels
down, text and graphics colors 1,2 and 3. Background color is color 0. It may
be set to a value from 0 to 16. Adding 16 to the background color number
gives a higher intensity off all the colors on the screen. When the
background changes, the entire screen's background changes immediately. Text
may be displayed via the hardware character set, user-defined characters or
character fonts. All types of graphics available.


COLORS IN MODE 4

          0 - current background color
          1 - GREEN
          2 - RED
          3 - YELLOW

Note: lower intensity YELLOW becomes BROWN.


COLORS IN MODE 5

          0 - current background color
          1 - CYAN
          2 - MAGENTA
          3 - WHITE


MODE 6

Graphics mode, 80 column text, 25 text lines, 640 pixels across, 200 pixels
down, background color is 0 (black), foreground color is 1, normally white,
can be set via TS:Xn command. Text may be displayed via hardware character
set, user-defined characters or character fonts. All types of graphics
available.


EXTENDED GRAPHICS ADAPTER

When using the IBM EGA there are several additional functions which can be
utilized. The EGA provides higher resolution, more colors and 80 column text
with 16 color graphics. The EGA also permits the modification of the colors
assigned to the 16 standard color numbers via control of the color palette.
In the EGA modes image graphics, sprites and user-defined characters are not
supported.  Character fonts are supported. Three additional screen modes are
supported. Selection of one of the EGA modes on a non-EGA system can give
unpredictable results.  The EGA supports modes 0 through 6 as described
above.


MODE 13

Graphics mode, 40 column by 25 line text. Graphics is 320 across by 200 down.
Colors are 0-15 for text and graphics. Text may be displayed via hardware
character set or character fonts. Turtle graphics can be used.  Image and
sprite graphics can not be used.


MODE 14

Graphics mode, 80 column by 25 line text. Graphics is 640 across by 200 down.
Colors are 0-15 for text and graphics. Text may be displayed via hardware
character set or character fonts. Turtle graphics can be used.  Image and
sprite graphics can not be used.


MODE 16

Graphics mode, 80 column by 25 line text. Graphics is 640 across by 350 down.
Colors are 0-15 for text and graphics.  Text may be displayed via hardware
character set or character fonts. Turtle graphics can be used.  Image and
sprite graphics can not be used.


EGA COLOR PALETTE

The EGA has logical color registers, or a color palette, as it is called.
There are 16 logical color registers which correspond to the sixteen logical
colors 0-15. Each register may contain an actual color number from 0 to 63
which tells what visible color is displayed for the logical color. The color
registers are active in all screen modes and can be set via the TS:Fn,a
command shown above. Changing the actual color for a logical color in which
data is currently displayed causes the display to change immediately. This
can be used to your advantage to create dynamic displays.


NORMAL AND XOR WRITING MODES

In graphics modes 4, 5 and 6 the text and turtle graphics can be displayed in
one of two ways.  The normal way is for text characters to replace the entire
character cell with the character and graphics output to replace each pixel.
An alternate way can be selected via the TS:O1 command shown above. XOR mode
causes a character or graphic element to be combined with the current display
data via a logical exclusive or operation. Using this mode a text character
can be placed over a graphic display without obscuring an entire 8 by 8 pixel
character cell.  Two characters can also be displayed in one character cell,
giving the effect of an overstrike capability. Two lines can intersect,
showing the point of intersection in the combined colors.


CHARACTER ANIMATION

The TS: statement can be used to construct animated
sequences by moving blocks of characters on the screen.
For more sophisticated animation it is recommended that
you use sprite animation, explained in the SPRITES section
of this document.

This example shows how to move a figure across the screen left to right then
right to left. The figure is a 4 letter block:

       WX
       YZ

However, it could be any user defined characters as well.  Notice that the
animation string is carefully laid out with spaces to insure that each redraw
of the figure completely overtypes the previous one so a trail is not left
behind.  The number after the D controls the speed of motion.

EXAMPLE 2: animate a block of characters

       TS:M1;B0;F1;*20(A WX/ YZ;WR;D5)
       TS:*20(WL;AWX /YZ ;D5)

MONOCHROME ADAPTER CARD

The various modes and colors apply only to the color adapter card.  On a
monochrome adapter the screen always works in 25 by 80 mode. It is
recommended that you use only mode 2 if your program is to run on a
monochrome adapter.

See also:  TYPE, GRAPHICS

USE - call a subroutine


       U: destination

The USE statement is used to call a subroutine.

USE jumps to the destination and saves the location of the statement after
the USE on the use-stack.  A subsequent END statement in the subroutine
causes a return to the statement after the USE.

The destination can be any of those described for JUMP, though the only one
which normally makes sense is a statement label.

USE statements can be nested. That is, a subroutine can call another
subroutine with another USE statement. The maximum nesting level is 32 levels
deep.

USE is similar to gosub in basic.

EXAMPLE: a subroutine call

       T:Typed first
       U:GLOSS
       T:Typed fourth
       E:
       . . .
       *GLOSS
       T:Typed second
       T:Typed third
       E:

EXAMPLE 2: String variable contains the name of             the subroutine to
call.

       X:"U:" !! X$

See also;  END, JUMP

VIDEO - call external driver program


       V: variable$

VIDEO is intended to allow a PILOT program to call a machine language
subroutine. It was originally used to call interface routines for video disc
and tape players. However, it could be used for many other purposes, since it
is actually a general purpose interface to any machine language program. (In
fact, most video devices do not need this type of driver program and can be
controlled directly by output from the FILE OUT statement.)

The only argument of a VIDEO statement is the name of a string variable.  The
string variable must have been dimensioned long enough to contain the machine
language subroutine and the subroutine must have been placed into the string.
The DX: op code must be used to dimension the string variable. This insures
that the string begins on a 16-byte boundary.

The VIDEO statement causes the machine language FAR CALL to be executed to
the first byte of the string. Upon entry to the subroutine the code segment
and data segment registers are equal and point to a segment which contains
the subroutine at offset zero.  Segment registers must not be modified upon
return from the subroutine. Other registers may be used without saving the
contents. The subroutine must return via a FAR RETURN op-code. Data can be
passed to/from the subroutine by the PILOT program in mutually decided
portions of the string variable itself.  The PILOT program can use
subscripting to deposit or fetch data in the locations within the string
designated by the subroutine.

A good way to get the subroutine into the string variable is to read it from
a disk file as shown in the first example below.  The machine language code
must be in memory image format and must be position independent since it may
be loaded anywhere.  Naturally, care should be taken in using this statement
as improper use can cause system failure. The DOS utility called EXE2BIN may
be of use in preparing the subroutine file.

Programming note: Since PILOT string variables are always terminated by a
null character, ( a zero byte) you may need to avoid placing zero bytes
within the data passed to and from the machine language subroutine. A zero
byte would look like the end of the string when using subscripting to access
bytes within the string.

EXAMPLE: Using the EXEC program of the Advanced Feature Library to execute
another DOS program as a subroutine.

       DX: EXEC$(600)
       FX: EXEC.BIN
       FI: 0,EXEC$
       C: EXEC$(9,80) = "TURBO XYZ"
       V: EXEC$

See also:  sample program SAMPLE4.PIL

WAIT - program delay

       W: expression
       WH:expression

WAIT causes a program delay for expression tenths of a second.  The delay is
prematurely ended if the student pushes a key.

EXAMPLE 1: WAIT 10 seconds or until a key is hit

       W:100

WAIT AND HOLD

Normally, if the WAIT is ended by the student pushing a key, the value of the
keypress is discarded and the program continues. Appending the H, or HOLD,
modifier to the WAIT changes this.  If the student pushes a key, the WH:
statement is ended, but the keypress is not discarded. Instead, it is left in
the type-ahead buffer so that it can be read by a subsequent ACCEPT
statement, or KEY function.

EXAMPLE 2: WAIT HOLD. This example shows a typical use for WAIT. At a pause
point within the program the student is instructed to push a key to go on.
The WH:30000 would wait essentially forever. When the student pushes a key,
the WH: ends and the  KEY function is used to see what key was pushed.  If it
is the ESC key, then the SYSX routine is called in much the same manner as it
would be called automatically by an ACCEPT.

       T:Push any key to go on.
       WH:30000
       U(KEY(0)=27):SYSX

Programming note: The TS:Dn command may be used to force a delay which can
not be interupted by the keyboard.

EXECUTE INDIRECT - execute a string


       XI: expression
       X: expression

EXECUTE INDIRECT allows you to construct a PILOT statement within a string,
then execute the statement. This very unique language feature turns out to be
an extremely powerful programming tool.

EXECUTE INDIRECT evaluates the expression to its string value.  Then the
string value is executed as if it were a PILOT statement.  The string may
contain any valid statement up to length 255. If the string is too long only
the first 255 characters are used.

Programming note: The "I" of "XI" may be omitted; it is allowed for
compatibility with other versions of PILOT.

EXAMPLE 1: Random problem selection. Assume that there are 10 problems, each
with a label PROB0, PROB1, etc. This statement could be used to select one at
random.

       X: "J:PROB" !! RND(10)


EXAMPLE 2: Save a frequently used graphic sequence in a string for repeated
use.

       C: BOX$="G:*4(F50;R90;F100;R90)"
       ...
       X: BOX$


EXAMPLE 3: Save viewport parameters in strings to simplify switching among
several viewports.

       C:QUES$ = "TS:V0,18,3,17;B1;F3"
       C:ANSW$ = "TS:V20,38,5,9;B2;F4"
       . . .
       X: QUES$
       T: What is the Magna Carta?
       X: ANSW$
       A:


EXAMPLE 4: A desk calculator constructed via the EXECUTE INDIRECT statement.

       *DESK
       TH:Enter an expression here:
       A:
       X: "C: X = " !! %B
       T:The result is #X
       J:DESK


See Also: SAMPLE1.PIL